Setting Custom Client Information

You can set custom client information—username and hostname—using the client side API VLSsetCustomData. This information is passed to the License Manager when a license request API or its variant is called. It can then be retrieved through the following ways:

>License Manager usage logs (in the user and host name fields of the log file)

>Query API (VLSgetClientInfo and VLSgetHandleInfo)

>WlmAdmin (for Windows only) and lsmon utilities

Function Prototype

LS_STATUS_CODE VLSsetCustomData
(
VLScustomData *pCustomData /*IN*/
);

Description

The API sets the custom client information—username and hostname. It takes a pointer to the structure VLScustomData.

To set the custom user information, call VLSsetCustomData before the license request API, but after the system initialization API. If the VLSsetCustomData API is not called at all (or not called in the correct sequence), the default user and host name is set.

If the client information is dynamic (for example, it changes for different clients), then you need to call the API individually for each client instance.

NOTE If the API VLSsetSharedId or VLSsetSharedIdValue is called, it overrides the value set by the VLSsetCustomData API. This is because the former API can also set the user name or host name-based on the sharedID value.

Parameters

VLScustomData is an IN parameter.

Before passing the pointer to this structure, ensure that structSz field of VLScustomData structure is initialized to the current size of VLScustomData.

typedef struct custom_data_struct
{
unsigned long  structSz;
char           username[VLS_CUSTOM_DATA_FIELD_SIZE + 1];
char           hostname[VLS_CUSTOM_DATA_FIELD_SIZE + 1];
}
VLScustomData;

Also note the following points:

>The custom user information cannot exceed 31 bytes.

NOTE Sentinel RMS does not read system user information (user name, host name, and X-display ID) beyond 31 characters.

>The custom user information cannot contain the following special characters:

•`~!@#$^&*()=+[]{}\|;:',/?<>"

•Space, tab, and new line

>Prior to v8.6.0, it was compulsory to specify both username and hostname while calling the API function, otherwise the API function returned the VLS_CALLING_ERROR. Now, you can choose to set either username or hostname, and leave the other one empty (instead the system default values will be sent by the license request API functions). Here are the possible combinations:

Username	Hostname	Outcome
Set	Set	Allowed
Set	Empty	Allowed
Empty	Set	Allowed
Empty	Empty	VLS_CALLING_ERROR

Returns

Error	Description
VLS_LIBRARY_NOT_INITIALIZED	When this API is called before VLSinitialize
VLS_CALLING_ERROR	>The username or hostname contain special characters (mentioned above). >The VLSsetCustomData API is called with NULL as its input parameter. >VLScustomData structure is passed in the VLSsetCustomData API without initializing the structSz field. >Either username or hostname (fields of the VLScustomData structure) is initialized with empty values and passed in the VLSsetCustomData API.

Error

Description

VLS_LIBRARY_NOT_INITIALIZED

When this API is called before VLSinitialize

VLS_CALLING_ERROR

>The username or hostname contain special characters (mentioned above).

>The VLSsetCustomData API is called with NULL as its input parameter.

>VLScustomData structure is passed in the VLSsetCustomData API without initializing the structSz field.

>Either username or hostname (fields of the VLScustomData structure) is initialized with empty values and passed in the VLSsetCustomData API.